---
order: 3
title: Sprite Mask
type: Graphics
group: 2D
label: Graphics/2D
---

The **Sprite Mask** component is used to apply masking effects to [Sprite Renderers](/en/docs/graphics/2D/spriteRenderer/) and [Text Renderers](/en/docs/graphics/2D/text/) in 3D/2D scenes.

<Image src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*J1Q9T5biHWgAAAAAAAAAAAAAehuCAQ/original" alt="070C8B9F-14E2-4A9A-BFEC-4BC3F2BB564F" style={{zoom: "67%"}} />

| Parameter          | Type   | Description                                                                                             |
| :----------------- | :----- | :------------------------------------------------------------------------------------------------------ |
| sprite             | number | A reference to the sprite                                                                              |
| alphaCutoff        | number | The lower limit of the effective alpha value (range: 0~1). Pixels with alpha values below this cutoff will be discarded |
| influenceLayers    | number | The mask layer(s) affected by this mask. Defaults to **Everything**, meaning it affects all mask layers |

<Callout type="warning">Currently, only sprite-based masks are supported to define the mask shape</Callout>

The hierarchical relationship between a **Sprite Mask** and its target components typically falls into three categories:

| influenceLayers     | maskLayer         | Takes Effect?                                                                                          |
| :------------------ | :---------------- | :----------------------------------------------------------------------------------------------------- |
| Layer0              | Layer0            | Equal → Takes effect                                                                                  |
| Layer1, Layer2      | Layer2, Layer3    | Intersection exists → Takes effect                                                                    |
| Layer4              | Layer5            | No intersection → Does not take effect                                                                |

<Callout type="info">[influenceLayers](/apis/core/#SpriteMask-influenceLayers): Layers affected by the sprite mask; [maskLayer](/apis/core/#SpriteRenderer-maskLayer): Mask layer of the target component</Callout>
<Callout type="info">If the mask still has no effect after adjusting layers, it might be because the target component's mask type is still set to the default (None). Update its [SpriteMaskInteraction](/apis/core/#SpriteMaskInteraction) accordingly</Callout>

## Usage

In the **[Hierarchy Panel](/en/docs/interface/hierarchy)**, **right-click** → **2D Object** → **Sprite Mask** to quickly create a node containing a Sprite Mask.

<Image src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*MnTWQ58Gr_QAAAAAAAAAAAAAehuCAQ/original" alt="070C8B9F-14E2-4A9A-BFEC-4BC3F2BB564F" style={{zoom: "67%"}} />

You can use the Sprite Mask in scripts as follows:

```typescript
// Create a mask entity
const spriteEntity = rootEntity.createChild(`spriteMask`);
// Add the SpriteMask component to the entity
const spriteMask = spriteEntity.addComponent(SpriteMask);
// Create a sprite object from a texture
const sprite = new Sprite(engine, texture);
// Assign the sprite
spriteMask.sprite = sprite;
// Discard pixels with alpha < 0.5 in the mask's texture
spriteMask.alphaCutoff = 0.5;
// Apply mask to all mask layers
spriteMask.influenceLayers = SpriteMaskLayer.Everything;
// Apply mask only to Layer0
spriteMask.influenceLayers = SpriteMaskLayer.Layer0;
// Apply mask to both Layer0 and Layer1
spriteMask.influenceLayers = SpriteMaskLayer.Layer0 | SpriteMaskLayer.Layer1;

// Set mask interaction type
spriteRenderer.maskInteraction = SpriteMaskInteraction.VisibleInsideMask;
// Assign the component to Layer0
spriteRenderer.maskLayer = SpriteMaskLayer.Layer0;
```